API Filtering and Pagination
Overview
IQM's API supports filtering and pagination in many of its endpoints. By either passing query or request parameters, results can be filtered for certain keywords or entity IDs, or, paginated by number of entries and page number.
Filtering and Pagination Parameters
The Parameters table below lists the most common filtering and pagination fields used in the IQM API. Their usage will vary based on the endpoint. They will often have a default value if a value is not specified. The default value will be listed as part of an endpoint's documentation if it exists.
| Parameters | |
|---|---|
ids integer | Filter results by entity ID (varies by endpoint) |
searchField / keywords string | Filter results by keyword |
limit / noOfEntries integer | Maximum number of entries returned per page |
pageNo integer | Page number for the returned data |
sortBy / order string | Sorts by ascending (+) or descending (-), the supported values will be listed |
offset integer | Specifies the number of rows of results to skip before data is retrieved. Functions counter to pageNo, and only one can be used at a time with limit/noOfEntries. First priority will be given to offset if used at the same time as pageNo |
Filtering Examples
In most cases, filtering the results will yield response data with totalRecords, the total number of records for the resource, and filteredRecords, the number of those total records filtered for this set of results.
Filtering by ID
Many endpoint will support filtering by some kind of entity ID. The exact parameter will vary based on the entity. For example, the Get List of Campaigns endpoint supports filtering by conversionId. When a Conversion ID is passed as a query, the endpoint returns all Campaign IDs that are associated with that Conversion at the top of the results.
https://app.iqm.com/api/v2/cmp/campaigns/data?conversionId=18
{
"statusCode": 200,
"responseObject": {
"totalRecords": 1498,
"data": [
{
"id": 176881,
"name": "Campaign to test duplicate copy",
"creativeTypeId": 14,
"campaignType": "CPV",
"status": "pending",
"advertiserId": 100419,
"created": 1620024156,
"modifiedDate": 1621571575,
"conversionId": 18
},
{
"id": 176880,
"name": "Campaign to test duplicate update",
"creativeTypeId": 14,
"campaignType": "CPV",
"status": "pending",
"advertiserId": 100419,
"created": 1620024050,
"modifiedDate": 1621571575,
"conversionId": 18
},
...
],
"filteredRecords": 1039
}
}
Filtering by Keywords
In this example the results are filtered with a search keyword. The Get State Segment endpoint uses the POST method, and therefore its pagination parameters will be passed with a JSON formatted request instead of a query.
{
"searchField": "California"
}
{
"success": true,
"data": {
"data": [
{
"id": 30212611,
"name": "Baja California Sur",
"parentId": 30100154,
"geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/.geojson"
},
{
"id": 30212610,
"name": "Baja California",
"parentId": 30100154,
"geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/.geojson"
},
{
"id": 30200005,
"name": "California",
"abbreviation": "CA",
"parentId": 30100001,
"geojsonUrl": "https://d3jme5si7t6llb.cloudfront.net/statedata/CA.geojson"
}
],
"totalRecords": 4964,
"filteredRecords": 3
}
}
Pagination Examples
Pagination allows you to specify how many results you want returned, what page of those results to return, and sort those results by various parameters.
Pagination by Number of Entries
The maximum number of entries returned can be specified with the noOfEntries (or sometimes limit) query parameter. Below two entries are retrieved from the Get List of Inventories endpoint.
https://app.iqm.com/api/v3/inv/inventories/list?noOfEntries=2
{
"success": true,
"data": {
"inventoryDataList": [
{
"id": 13097078,
"name": "com.twitter.android",
"publisher": "adx_pub-3661441281163245",
"appId": "com.twitter.android",
"inventoryType": "Android App",
"impressions": 2698270955,
"reach": 56406049,
"videoPercentage": 0.0,
"displayPercentage": 0.0
},
{
"id": 34520,
"name": "METROPCS-METROZONE",
"publisher": "adx_pub-2964924015572549",
"appId": "com.metropcs.metrozone",
"inventoryType": "Android App",
"impressions": 2319549000,
"reach": 115747223,
"videoPercentage": 22.769272,
"displayPercentage": 48.073381
}
]
}
}
Pagination by Page Number
When the possible number of results exceeds the limit that can be returned, there will be a pageNo parameter to specify which page of results will be returned. Keeping with the example in the previous section, if a page number of "2" is appended in addition to the two entries, the next two records will be retrieved.
https://app.iqm.com/api/v3/inv/inventories/list?noOfEntries=2&pageNo=2
{
"success": true,
"data": {
"inventoryDataList": [
{
"id": 13106651,
"name": "X",
"publisher": "adx_pub-3661441281163245",
"appId": "333903271",
"inventoryType": "IOS App",
"impressions": 1413114383,
"reach": 57020310,
"videoPercentage": 0.020887,
"displayPercentage": 0.0
},
{
"id": 4777647,
"name": "Samsung TV Plus Free",
"publisher": "Samsung",
"appId": "g15147002586",
"inventoryType": "Other App",
"impressions": 583064989,
"reach": 24606677,
"videoPercentage": 100.0,
"displayPercentage": 0.0
}
]
}
}
Pagination by Sorting the Results
Lists of results can often be sorted by a specified parameter. Using the sortBy query in the Get List of Campaigns endpoint, the returned list of Campaigns can be sorted by ascending or descending by appending a + or - symbol to the desired parameter. In this example, the results are sorted by -created: the descending order of creation date.
https://app.iqm.com/api/v2/cmp/campaigns/data?sortBy=-created
{
"statusCode": 200,
"responseObject": {
"totalRecords": 1498,
"data": [
{
"id": 176881,
"name": "Campaign to test duplicate copy",
"creativeTypeId": 14,
"campaignType": "CPV",
"status": "pending",
"advertiserId": 100419,
"created": 1620024156,
"modifiedDate": 1621571575,
"conversionId": 18
},
{
"id": 176880,
"name": "Campaign to test duplicate update",
"creativeTypeId": 14,
"campaignType": "CPV",
"status": "pending",
"advertiserId": 100419,
"created": 1620024050,
"modifiedDate": 1621571575,
"conversionId": 18
},
{
"id": 176879,
"name": "to test campaign duplication",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "pending",
"advertiserId": 100419,
"created": 1620023582,
"modifiedDate": 1620024188
},
{
"id": 176148,
"name": "campaign to test Inventory group and all device type",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "pending",
"advertiserId": 100419,
"created": 1618990887,
"modifiedDate": 1618992828
},
{
"id": 173357,
"name": "test cb",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "running",
"advertiserId": 100001,
"created": 1617170692,
"modifiedDate": 1619433624
},
{
"id": 173353,
"name": "test cb",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "running",
"advertiserId": 100001,
"created": 1617163055,
"modifiedDate": 1619433624
},
{
"id": 173318,
"name": "test cb1",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "running",
"advertiserId": 100001,
"created": 1617130075,
"modifiedDate": 1619433624
},
{
"id": 173317,
"name": "test cb",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "running",
"advertiserId": 100001,
"created": 1617126490,
"modifiedDate": 1619433624
},
{
"id": 173316,
"name": "test old cb",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "running",
"advertiserId": 100001,
"created": 1617125771,
"modifiedDate": 1619433624
},
{
"id": 169459,
"name": "test daily",
"creativeTypeId": 11,
"campaignType": "CPM",
"status": "pending",
"advertiserId": 100419,
"created": 1611734667,
"modifiedDate": 1618992828
}
],
"filteredRecords": 1039
}
}